Tools Plus supports the use of scroll bars on any window created by the WindowOpen procedure. Scroll bars are created on the current window by the NewScrollBar procedure. Each scroll bar is referenced by a unique scroll bar number, that can be from 1 to 255. This number is specified when the scroll bar is created, and refers to the specific scroll bar until that scroll bar is deleted. Note that the scroll bar number is related to its associated window. This means that two different windows can each have a scroll bar numbered “1” without interfering with each other. Whenever a scroll bar is used by the user, the PollSystem function reports the scroll bar number, the part (see below) that was used, and its window number.
Scroll bars can be either horizontal or vertical, and are made up of five distinct parts:
[1] up arrow (arrow pointing up on vertical scroll bars, or left on
horizontal scroll bars)
[2] down arrow (arrow pointing down on vertical scroll bars, or right
on horizontal scroll bars)
[3] thumb (movable tab situated between the up arrow and down arrow)
[4] “page up” region (the region between the up arrow and the thumb)
[5] “page down” region (the region between the down arrow and the
thumb)
A scroll bar’s minimum and maximum settings can be obtained by the GetScrollBarMin and GetScrollBarMax functions. The current value can be obtained by the GetScrollBarVal function. Conversely, these values can be set by using the SetScrollBarMin, SetScrollBarMax, and SetScrollBarVal procedures.
When a scroll bar is no longer required, it is deleted by the DeleteScrollBar procedure, which releases the memory used by the scroll bar. This is done automatically if a window is closed.
Scroll Bar States
`````````````````
A scroll is enabled or disabled by the EnableScrollBar procedure. When a window is inactive, all the associated scroll bars are automatically hidden (only the outline is displayed) and cannot be selected. When the window is activated, the scroll bars return to their normal status as set by your application.
Handling Scroll Bars
````````````````````
Your application specifies if a scroll bar is enabled or disabled. When a window in inactive, Tools Plus disables all scroll bars. When the window is activated again, all the scroll bars regain their correct status as specified by your application. If a window contains a scroll bar along its right side and/or bottom (such as on word processing documents and spreadsheets), these scroll bars are automatically sized and moved if the user drags the window’s “size box” (providing that the window has a “size box”) or clicks the “zoom box.”.
The PollSystem function is used to constantly inquire about any events that have occurred, including scroll bar interaction. If any part of a scroll bar is selected, it will be reported by PollSystem. When the user moves the scroll bar’s thumb, GetScrollBarVal should be called to obtain the scroll bar’s new value. Simply moving the thumb, then leaving it in the same position does not generate an event. If the user clicks and holds the up arrow, “page up” region, down arrow, or “page down” region, PollSystem reports an event for this part of the scroll bar each time PollSystem is called.
Warning: If you have obtained a handle to a scroll bar, do not change
ScrollBar specifies the scroll bar number (from 1 to 255) that will be created in the current window. Once a scroll bar is created, it will be referenced by this scroll bar number. If a scroll bar has been previously created in the current window using the same number, it will be replaced with a new scroll bar as specified by the parameters in the NewScrollBar procedure. If the current window doesn’t belong to your application, or if no windows are open, NewScrollBar does nothing.
Left, top, right, and bottom define a rectangle in local co-ordinates that determines the scroll bar’s size and location in the window. These parameters can be seen as two corners; the upper left-hand corner (left,top) and the bottom right-hand corner (right,bottom). A scroll bar will be vertical or horizontal depending on whether the height or width of the rectangle is greatest. Scroll bars should be exactly 16 pixels wide, so there should be a 16 pixel difference between the scroll bar’s top and bottom, or left and right side. If there isn’t, the scroll bar will be scaled to fit into the rectangle and will not look as attractive. Also, the scroll bar must be at least 40 pixels long in order to contain the up arrow, down arrow, and thumb.
For windows with a ProcID of documentProc (i.e. with a “size” box) two special scroll bars may be created; one along the right side of a window and/or one along the bottom. These scroll bars are special because they are automatically sized and moved if the window’s size is changed. Here are some useful measurements for these specialized scroll bars:
Right scroll bar (left,top) To place the top of the scroll bar exactly
below the window’s title bar, give left
the value of the window’s width - 15, and
top the value of -1. (The window’s width
and height can be obtained from the
WindowStatus procedure.)
(right,bottom) To place the bottom of the scroll bar
exactly at the upper edge of the “size
box”, give right the value of the window’s
width + 1, and bottom the value of the
window’s height - 14. If these exact
dimensions are not used, the scroll bar
will not be sized or moved when the
window’s size is changed.
Bottom scroll bar (left,top) To place the left side of the scroll bar
exactly at the window’s left edge, give
left the value of - 1, and top the value
of the window’s height -15.
(right,bottom) To place the right side of the scroll bar
exactly at the left edge of the “size
box,” give right the value of the window’s
width - 14, and bottom the value of the
window’s height + 1. If these exact
dimensions are not used, the scroll bar
will not be sized or moved when the
window’s size is changed.
EnabledFlag specifies if the scroll bar is enabled or disabled when the window is active. When a scroll bar is disabled, the thumb and toned “page up” and “page down” regions disappear, and the scroll bar cannot be used by the operator. The two constants that can be used for this purpose are enabled and disabled . All scroll bars automatically become hidden (only the outline is shown) when the window containing them becomes inactive. When the window is activated, the scroll bars will assume their normal state as set by the NewScrollBar procedure, and subsequent calls to the EnableScrollBar procedure.
Minimum declares the scroll bar’s minimum setting limit.
Value defines the scroll bar’s current value. The current value must be greater than or equal to the minimum setting, and less than or equal to the maximum setting.
Maximum declares the scroll bar’s maximum setting limit. The maximum setting limit must be greater than the minimum setting limit.
Also see: NewScrollBarRect.
Note: Tools Plus makes no attempt to control the placement of scroll
bars or to protect them once they have been created. It is the
programmer’s responsibility to ensure that scroll bars are of
sufficient length to contain the up/down arrows and the thumb, and
that their placement within the window is reasonable and does not
conflict with other objects. Furthermore, you should not allow
your application’s text and drawing processes to interfere with
scroll bars. Windows with a “size box” should not allow scroll
bars to be obscured or hidden by making the window too small.
NewScrollBarRect is identical to the NewScrollBar procedure, except that it accepts the Bounds rectangle in place of the individual left, top, right and bottom co-ordinates.
ScrollBar specifies the scroll bar number (from 1 to 255) that is deleted from the current window. If the current window doesn’t belong to your application, or if no windows are open, or if the scroll bar does not exist in the current window, DeleteScrollBar does nothing.
ScrollBar specifies the scroll bar number (from 1 to 255) that is to be affected in the current window. If the current window doesn’t belong to your application, or if no windows are open, or if the scroll bar does not exist in the current window, EnableScrollBar does nothing.
EnabledFlag specifies if the scroll bar is enabled or disabled when the window is active. When a scroll bar is disabled, the thumb and toned “page up” and “page down” regions disappear and the scroll bar cannot be selected by the user. The two constants that can be used for this purpose are enabled and disabled .
All scroll bars automatically become disabled if the window containing them becomes inactive. When the window is activated, the scroll bars assume their normal state as set by the EnableScrollBar procedure.
function GetScrollBarMin(ScrollBar: INTEGER): INTEGER;
ScrollBar specifies the scroll bar number (from 1 to 255) that will be queried in the current window.
GetScrollBarMin returns the value of a scroll bar’s minimum setting limit. If the current window doesn’t belong to your application, or if no windows are open, or if the scroll bar does not exist in the current window, GetScrollBarMin will return a value of -maxInt.
ScrollBar specifies the scroll bar number (from 1 to 255) that will be affected in the current window. If the current window doesn’t belong to your application, or if no windows are open, or if the scroll bar does not exist in the current window, SetScrollBarMin does nothing.
Minimum specifies the scroll bar’s new minimum setting limit. The scroll bar’s current value and maximum setting are automatically adjusted (if necessary) to be consistent with the new minimum setting.
function GetScrollBarMax(ScrollBar: INTEGER): INTEGER;
ScrollBar specifies the scroll bar number (from 1 to 255) that will be queried in the current window.
GetScrollBarMax returns the value of a scroll bar’s maximum setting limit. If the current window doesn’t belong to your application, or if no windows are open, or if the scroll bar does not exist in the current window, GetScrollBarMax will return a value of maxInt.
ScrollBar specifies the scroll bar number (from 1 to 255) that will be affected in the current window. If the current window doesn’t belong to your application, or if no windows are open, or if the scroll bar does not exist in the current window, SetScrollBarMax does nothing.
Maximum specifies the scroll bar’s new maximum setting limit. The scroll bar’s current value and minimum setting are automatically adjusted (if necessary) to be consistent with the new maximum setting.
function GetScrollBarVal(ScrollBar: INTEGER): INTEGER;
ScrollBar specifies the scroll bar number (from 1 to 255) that will be queried in the current window.
GetScrollBarVal returns a scroll bar’s current value. If the current window doesn’t belong to your application, or if no windows are open, or if the scroll bar does not exist in the current window, GetScrollBarVal will return a value of maxInt.
ScrollBar specifies the scroll bar number (from 1 to 255) which is to be affected in the current window. If the current window doesn’t belong to your application, or if no windows are open, or if the scroll bar does not exist in the current window, SetScrollBarVal does nothing.
Value specifies the scroll bar’s new current value. The scroll bar’s minimum and maximum settings are automatically adjusted (if necessary) to be consistent with the new current value.
